Skip to main content

​
Introduction

Check the status of your video generation tasks and retrieve download URLs when completed. This guide covers polling strategies and status interpretation for all video types (Avatar Videos, Product Videos, and Template Videos). Use webhooks for instant notifications or polling for status checks.

​
Key Features

Real-Time Status

Get current processing status instantly

Video Download

Retrieve final video URLs when ready

Error Details

Get detailed error messages if failed

Metadata

Access duration, cover images, and more

​
Workflow Overview

Video generation follows a standard status flow:
Videos typically take 2-10 minutes to generate depending on length and complexity. Use webhooks for instant notifications instead of polling.

​
Quick Start

Video TypeGet Status EndpointDocumentation
Avatar VideosGET /v2/avatar_video/{id}API Reference
Product VideosGET /v2/product_video/{product_video_id}API Reference
Template VideosGET /v2/template_video/{video_id}API Reference

​
Status Values

StatusDescriptionNext Action
pendingQueued, not started yetWait and poll again
processingCurrently renderingWait and poll again
completedVideo is readyDownload from video_url
failedError occurredCheck error message
Recommended: Use [Webhooks](/api-reference/v2/API Documentation/WebhookIntegration) instead of polling for better performance and instant notifications.

​
Code Examples

​
Scenario 1: Check Avatar Video Status

Poll for avatar video completion: 
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatar_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
Response (Processing): 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "processing",
    "created_at": 1732806631
  }
}
Response (Completed): 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/video_123456.jpg",
    "duration": 30,
    "created_at": 1732806631
  }
}
When status is completed, download the video from video_url.

​
Scenario 1: Check Product Video Status

curl --request GET \
  --url 'https://api.jogg.ai/v2/product_video/pv_789012' \
  --header 'x-api-key: YOUR_API_KEY'
Response (Completed): 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "id": "pv_789012",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/pv_789012.mp4",
    "cover_url": "https://res.jogg.ai/covers/pv_789012.jpg",
    "video_duration": 30.5,
    "created_at": 1732806631
  }
}
Response (Failed): 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "id": "pv_789012",
    "status": "failed",
    "error": {
      "code": 50000,
      "message": "Insufficient media quality for video generation"
    },
    "created_at": 1732806631
  }
}
If status is failed, check the error object for details and retry with corrected parameters.

​
Scenario 1: Check Template Video Status

curl --request GET \
  --url 'https://api.jogg.ai/v2/template_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
Response (Completed): 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/cover_123456.jpg",
    "duration": 30,
    "created_at": 1732806631
  }
}

​
Use Case Examples

When to Use: When webhooks are not available or you need immediate status checks.Recommended Schedule:
  • Wait 10-15 seconds before first poll
  • Poll every 10 seconds for first minute
  • Increase to 30 seconds, then 60 seconds
  • Stop after 10 minutes and check for issues
Do not poll faster than every 5 seconds to avoid rate limiting.
When to Use: Recommended for production applications.Advantages:
  • ✅ No polling overhead
  • ✅ Instant notifications
  • ✅ Reduced API calls
  • ✅ Better scalability
  • ✅ Lower latency
See [Webhook Integration](/api-reference/v2/API Documentation/WebhookIntegration) for setup.
When to Use: Checking status of multiple videos.Strategy:
  • Use list endpoints (/v2/template_videos, /v2/product_videos) to get status of multiple videos
  • Filter by status to find completed/failed videos
  • Process completed videos, retry failed ones

​
Tips for Best Results

Polling Strategy:
  • Wait 10-15 seconds before first poll (videos rarely complete faster)
  • Poll every 10 seconds for first minute
  • Increase to 30 seconds, then 60 seconds
  • Stop after 10 minutes and check for issues
Use Webhooks Instead:
  • Use [Webhooks](/api-reference/v2/API Documentation/WebhookIntegration) instead of polling for better performance
  • Instant notifications when videos are ready
  • Reduced API calls and better scalability
  • Lower latency for end users
Polling Schedule:
Time ElapsedPoll IntervalReason
0-60sEvery 10sVideos might complete quickly
1-5minEvery 30sNormal processing time
5-10minEvery 60sHandling queue delays
> 10minStopLikely an issue, check logs
Webhook vs Polling:

​
Response Field Reference

​
Completed Video Response

FieldTypeDescription
video_id / idstringVideo identifier
statusstringCurrent status (completed)
video_urlstringDownload URL for MP4 file
cover_urlstringThumbnail/cover image URL
duration / video_durationnumberVideo length in seconds
titlestringVideo title (if provided)
created_atintegerUnix timestamp of creation

​
Processing Video Response

FieldTypeDescription
video_id / idstringVideo identifier
statusstringCurrent status (pending or processing)
created_atintegerUnix timestamp

​
Failed Video Response

FieldTypeDescription
video_id / idstringVideo identifier
statusstringStatus (failed)
error.codeintegerError code
error.messagestringHuman-readable error description
created_atintegerUnix timestamp

​
Troubleshooting

Error: Video ID does not existSolutions:
  • Verify video ID is correct
  • Check if video creation succeeded
  • Video IDs are case-sensitive
  • Ensure you’re using the correct endpoint for video type
Error: Status is failed with error objectCommon Causes:
  • Insufficient media quality
  • Invalid avatar/voice combination
  • Script too long for video length
  • API quota exceeded
  • Invalid template variables
Solutions:
  • Check error message in response
  • Verify all input parameters are valid
  • Retry with corrected parameters
  • Check Error Handling Guide
Issue: Video stuck in processing > 15 minutesSolutions:
  • Contact support with video ID
  • Check Status Page
  • Retry video creation
  • Verify video type and parameters
Error: Too many requestsSolutions:
  • Reduce polling frequency (minimum 5 seconds between polls)
  • Use webhooks instead of polling
  • Check Rate Limits
  • Implement exponential backoff

Webhook Integration

Better alternative to polling

Create Avatar Videos

Start video generation

Error Handling

Understand error responses

Rate Limits

API usage limits